.\" $Id: PAPI_library_init.3,v 1.16 2004/10/01 18:26:20 you Exp $
.TH PAPI_library_init 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
.nf
PAPI_library_init   \- initialize the PAPI library.
PAPI_is_initialized \- check for initialization.
.fi

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int PAPI_library_init(int " version ");"
.BI "int PAPI_is_initialized(void);"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_library_init(C_INT\  check )
.BI PAPIF_is_initialized(C_INT\  check )
.fi

.SH DESCRIPTION
.B "PAPI_library_init()"
initializes the PAPI library. It must be called
before any low level PAPI functions can be used. If your application
is making use of threads
.BR "PAPI_thread_init" (3)
must also be called prior to making any calls to the library other 
than 
.BR PAPI_library_init() .
.LP
.B PAPI_is_initialized() 
returns the status of the PAPI library. 
The PAPI library can be in one of three states, as described under RETURN VALUES.

.SH ARGUMENTS
.I "version"
-- upon initialization, PAPI checks the argument against the internal value of
.B "PAPI_VER_CURRENT"
when the library was compiled. This guards against portability
problems when updating the PAPI shared libraries on your system.

.SH RETURN VALUES
.B "PAPI_library_init"
: On success, this function returns 
.B "PAPI_VER_CURRENT" .
A positive return code other than 
.B PAPI_VER_CURRENT 
indicates a library version mis-match.
A negative error code indicates an initialization error.

.B "PAPI_is_initialized":
.LP
.B PAPI_NOT_INITED
 -- PAPI has not been initialized
.LP
.B PAPI_LOW_LEVEL_INITED
 -- PAPI_library_init has been called
.LP
.B PAPI_HIGH_LEVEL_INITED
 -- a high level PAPI function has been called


.SH ERRORS
.B PAPI_is_initialized
never returns an error.
.LP
.B PAPI_library_init
can return the following:
.TP
.B "PAPI_EINVAL"
.I "papi.h"
is different from the version used to 
compile the PAPI library.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.
.TP
.B "PAPI_ESBSTR"
This substrate does not support the underlying hardware.
.TP
.B "PAPI_ESYS"
A system or C library call failed inside PAPI, see the 
.I "errno"
variable.

.SH EXAMPLES
.LP
.nf
.if t .ft CW
int retval;

/* Initialize the library */

retval = PAPI_library_init(PAPI_VER_CURRENT);

if (retval != PAPI_VER_CURRENT && retval > 0) {
  fprintf(stderr,"PAPI library version mismatch!\en");
  exit(1); }

if (retval < 0) 
  handle_error(retval);

retval = PAPI_is_initialized();

if (retval != PAPI_LOW_LEVEL_INITED) 
  handle_error(retval);
.if t .ft P
.fi

.SH BUGS
If you don't call this before using any of the low level PAPI calls,
your application could core dump.

.SH SEE ALSO
.BR PAPI_thread_init "(3),"
.BR PAPI "(3)"

